$Revision: 1.3 $

 Format du fichier de construction (build.ini)


 ## Syntaxe du fichier :

  Le format utilise se veut simple, a la fois facilement manipulable par
  les outils de gestion de build, et humainement modifiable. La syntaxe des
  fichier "*.ini" a donc ete choisie.

  C.a.d un fichier est compose de sections, rassemblant une ou plusieurs
  options.

  [Section_1]
  optionA       = valeur
  optionB       = valeur
  optionC       = valeur

  [Section_2]
  optionS       = 
  optionA       = valeur
  optionX       = valeur

  (...)


  Il est possible de definir des "variables" afin de factoriser certaines
  valeurs. Si definit dans la section [DEFAULT] ces variables sont
  accessibles de toutes les autres sections du fichier, sinon, une variable
  n'est accessible qu'au sein de la section ou elle est definie.
  les variables ont le format suivant: %(nom)s
  le 's' final est OBLIGATOIRE, sinon le parser se plaindra.

  [DEFAULT]
  rootdir       = D:

  [Section_1]
  file          = %(rootdir)s\build\%(foo)s.txt
  foo           = bar

  => apres resolution: file = D:\build\bar.txt


 ## Liste de taches

  Le processus de construction de l'archive (ici auto extractible)
  ditribuable passe par les etapes suivantes, dans l'ordre :
  
  - recuperation de fichiers source via CVS
  - "versioning" de fichiers binaires (inscription du n de version)
  - generation de fichiers de ressources (images, contenu multimedia,..)
  - compilation de fichiers sources
  - generation de l'installateur (rationnal rose setup factory 6)

  Ces etapes se decomposent en taches unitaires. Le fichier de construction
  assimile ces etapes a des listes de taches.
  
  Chaque liste est constituee :
   - D'une part, d'une section "mere" definissant le nombre de taches et
    factorisant les proprietes communes a la plupart des taches de la liste.
   - D'une serie de section "filles", chacune representant une tache de la
    liste.

  [CvsTasks]
  count           = 3        # 3 taches : CvsTask_0, CvsTask_1 et CvsTask_2
  enabled         = True
  comments        = dummy cvs tasks list
  cmdextra        = 
  notafter        = 
  client          = C:\Program Files\TortoiseCVS\cvs.exe
  command         = 
  destdir         = D:\Trash_DCU\machin truc
  tag             = 
  logfile         = test_buildfile.txt
  cvsroot         = :ext:benoitk@10.0.0.128:/home/netasq/sources
  cvsrsh          = ssh
  
  [CvsTask_0]
  enabled         = False    # tache desactive
  module          = unittest
  command         = checkout
  cmdextra        = -Q

  [CvsTask_1]
  enabled         = True
  module          = unittest
  command         = checkout
  tag             = V_5_1_0_BETA10
  logfile         = 

  (...)


  Remarque : les chemins de fichier relatifs seront resolus relativement a
  l'emplacement du fichier de construction; l'utilisation de chemins absolus
  est plus que vivement conseill.

  Dans cet exemple, la section "mere" definit client cvs, cvsroot, fichier
  de traces et valeur de la variable d'environnement CVS_RSH  utiliser par
  defaut par les taches.
  Ainsi la tache CvsTask_0 sera vue comme :

  [CvsTask_0]
  cmdextra        = -Q
  enabled         = False    # tache desactive
  module          = unittest
  client          = C:\Program Files\TortoiseCVS\cvs.exe
  command         = checkout
  destdir         = D:\Trash_DCU\machin truc
  logfile         = test_buildfile.txt
  cvsroot         = :ext:benoitk@10.0.0.128:/home/netasq/sources
  cvsrsh          = ssh

  Dans le cas de la tache CvsTask_1, la redefinition de la propriete
  "logfile" desactive la recuperation des messages renvoyes par le systeme.

  Une liste d'un type particulier s'attend a ce que ses elements soient du
  meme type (une liste de taches cvs n'est normalement constituee que de
  sous taches cvs), or il est tout a fait possible de melanger les taches
  au sein d'une liste; dans ce cas, la section definissant une tache de type
  different doit explicitement preciser son type par l'option "tasktype"

  ## sections complementaires

  En plus des sections concernant les taches, on trouve trois sections
  supplementaires: 'DEFAULT', 'FileVersion' et 'Mailing'.
  la presence de la section 'FileVersion' est recommandee.
  
  [FileVersion]
  version         = 1.0

  'FileVersion' ne definit que la propriete version, correspondant a la
  version de la structure du fichier (en prevision d'eventuelles
  modifications du mecanisme d'analyse du fichier)


  [DEFAULT]
  rootdir         = D:\build
  src_dir         = %(rootdir)s\src
  bin_dir         = %(rootdir)s\bin

  la section 'DEFAULT', presentee plus haut, definit des variables
  accessibles par l'ensemble des sections du fichier. Aucune option
  particuliere n'est attendue.


  [Mailing]
  enabled         = True
  logfile         = logfile.txt
  sender          = someone@netasq.com
  recipients      = labo.ihm@netasq.com
  success         = build success :-)
  failure         = build failure :-(

  la section 'Mailing' definit les parametres utiles et necessaires a
  l'envoi de courrier pour prevenir de la reussite ou de l'echec de la
  procedure de construction.
  Si cette section n'est pas presente, aucun mail ne sera envoye; de meme
  si cette section est desactivee "enabled = False", ou invalide (par ex.
  si aucun destinataire, "recipients", n'est precis).


  
  ## Details des sections

  * FileVersion
  
   options obligatoires :
    - version                   version de la structure du fichier
    
   options complementaires :
    aucune option particuliere

  * DEFAULT
  
   options obligatoires :
    aucune option particuliere
    
   options complementaires :
    aucune option particuliere

  * Mailing
  
   options obligatoires :
    - enabled                   True/False
    - recipients                adresses mails des destinataires
    
   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces a attacher au mail
    - sender                    adresse mail de l'expediteur
     si non precise, forgee a partir de l'utilisateur courant
    - success                   sujet du mail si la procedure de
     construction est un succes
    - failure                   sujet du mail si la procedure de
     construction a echou


  * CvsTasks

   options obligatoires :
    - count                     nombre de sous taches definies
    - enabled                   True/False

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type de la liste (normalement: 'cvsTask')
    - client                    chemin vers le client cvs
    - command                   commande cvs
    - cmdextra                  options a passer au client CVS
    - cvsroot                   CVSROOT
    - cvsrsh                    CVS_RSH
    - destdir                   repertoire de destination
    - notafter                  date limite
    - tag                       tag

   exemple :
    [CvsTasks]
    count           = 1
    tasktype        = cvsTask
    enabled         = True
    comments        = cvs tasks list dummy test
    logfile         = %(log_file)s
    client          = C:\Program Files\TortoiseCVS\cvs.exe
    command         =
    cmdextra        =
    cvsroot         = %(cvs_root)s
    cvsrsh          = ssh
    destdir         =
    notafter        =
    tag             =

  ** CvsTask_x

   options obligatoires :
    - enabled                   True/False
    - module                    module a recuperer

   options obligatoires si non definies par la section "mere"
    - client                    chemin vers le client cvs
    - command                   commande cvs

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type 'cvsTask'
     OBLIGATOIRE si le type differe de celui de la section "mere"
    - cmdextra                  options a passer au client CVS
    - cvsroot                   CVSROOT, si aucun CVSROOT n'est precis, on
     utilise la valeur du systeme (variable d'environnement)
    - cvsrsh                    CVS_RSH, si aucun CVS_RSH n'est precis, on
     utilise la valeur du systeme (variable d'environnement)
    - destdir                   repertoire de destination
    - notafter                  date limite
    - tag                       tag, 'HEAD' si non precis

   exemple :
    [CvsTask_0]
    enabled         = True
    module          = %(cvs_pkg)s
    command         = checkout
    cmdextra        = -q
    destdir         = %(cvs_dir)s
    tag             = %(cvs_tag)s


  * VrsTasks

   options obligatoires :
    - count                     nombre de sous taches definies
    - enabled                   True/False

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type de la liste (normalement: 'vrsTask')
    - modifier                  chemin vers resModifier.exe
    - cmdextra                  options complementaires
    - companyname               Res info : CompanyName
    - legalcopyright            Res info : LegalCopyright
    - filedescription           Res info : FileDescription
    - fileversion               Res info : FileVersion (ex: 1.0.0.0)
    - productversion            label de l'application (alpha, beta, rc...)

   exemple :
    [VrsTasks]
    count           = 1
    tasktype        = vrsTask
    enabled         = True
    comments        = vrs tasks list dummy test
    logfile         = %(log_file)s
    modifier        = %(src_dir)s\build\extrafiles\ResModifier.exe
    cmdextra        =
    companyname     = NETASQ - Secure Internet Connectivity
    legalcopyright  = (c)Copyright 2003-2004 NETASQ
    filedescription =
    fileversion     =
    productversion  =

  ** VrsTask_x

   options obligatoires :
    - enabled                   True/False
    - directory                 repertoire racine a traiter reccurssivement

   options obligatoires si non definies par la section "mere"
    - modifier                  chemin vers resModifier.exe

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type 'vrsTask'
     OBLIGATOIRE si le type differe de celui de la section "mere"
    - cmdextra                  options complementaires
    - companyname               Res info : CompanyName
    - legalcopyright            Res info : LegalCopyright
    - filedescription           Res info : FileDescription
    - fileversion               Res info : FileVersion (ex: 1.0.0.0)
    - productversion            label de l'application (alpha, beta, rc...)

   exemple :
    [VrsTask_0]
    enabled         = True
    directory       = %(src_dir)s\firewall
    filedescription = Netasq Global Administration Interface
    fileversion     = 1.1.0.0
    productversion  = test script


  * ResTasks

   options obligatoires :
    - count                     nombre de sous taches definies
    - enabled                   True/False

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type de la liste (normalement: 'resTask')
    - manager                   chemin vers resManager.exe
    - cmdextra                  options complementaires
    - inifile                   fichier .ini
    - resdir                    repertoire de ressources
    - srcdir                    ???

   exemple :
    [ResTasks]
    count           = 1
    tasktype        = resTask
    enabled         = True
    comments        = res tasks list dummy test
    logfile         = %(log_file)s
    manager         = %(src_dir)s\build\ResManager.exe
    cmdextra        =
    inifile         = %(src_dir)s\build\ResManager.ini
    resdir          = %(src_dir)s\compo\netasq\ihmresources\res
    srcdir          = %(src_dir)s\compo\netasq\ihmresources\src

  ** ResTask_x

   options obligatoires :
    - enabled                   True/False
    - project                   projet resManager .rmc

   options obligatoires si non definies par la section "mere"
    - manager                   chemin vers resManager.exe

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type 'resTask'
     OBLIGATOIRE si le type differe de celui de la section "mere"
    - cmdextra                  options complementaires
    - inifile                   fichier .ini
    - resdir                    repertoire de ressources
    - srcdir                    ???

   exemple :
    [ResTask_0]
    enabled         = True
    project         = %(src_dir)s\compo\netasq\ihmresources\res\ASQResources.rmc


  * DccTasks

   options obligatoires :
    - count                     nombre de sous taches definies
    - enabled                   True/False

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces par defaut
    - tasktype                  type de la liste (normalement: 'dccTask')
    - compiler                  chemin vers le compilateur
    - cmdextra                  options a passer au compilateur
    - bindir                    destination des binaires
    - dcudir                    destination des fichiers .dcu
    - cfgfile                   fichier de configuration .cfg
    
    - mad_patch                 chemin vers l'utilitaire de patch mad except
    - mad_mesfile               fichier de config mad except .mes
    - mad_mapfile               fichier .map
    - mad_extra                 options complementaires

   exemple :
    [DccTasks]
    count           = 29
    tasktype        = dccTask
    enabled         = True
    comments        = dcc tasks list dummy test
    logfile         = %(log_file)s
    compiler        = C:\Program Files\Borland\Delphi7\Bin\DCC32.EXE
    cmdextra        = -B -Q
    bindir          = %(bin_dir)s
    dcudir          = %(dcu_dir)s
    cfgfile         = %(cfg_file)s
    mad_patch       = C:\Program Files\madCollection\madExcept\Tools\madExceptPatch.exe
    mad_mesfile     = %(mes_file)s
    mad_mapfile     =
    mad_extra       =

  ** DccTask_x

   options obligatoires :
    - enabled                   True/False
    - project                   projet a compiler

   options obligatoires si non definies par la section "mere"
    - compiler                  chemin vers le compilateur

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type 'dccTask'
     OBLIGATOIRE si le type differe de celui de la section "mere"
    - cmdextra                  options a passer au compilateur
    - bindir                    destination des binaires
    - dcudir                    destination des fichiers .dcu
    - cfgfile                   fichier de configuration .cfg
    
    - mad_patch                 chemin vers l'utilitaire de patch mad except
    - mad_mesfile               fichier de config mad except .mes
    - mad_mapfile               fichier .map
    - mad_extra                 options complementaires

   exemple :
    [DccTask_28]
    enabled         = True
    project         = %(src_dir)s\firewall\globalupdate\src\GlobalAdmin.dpr


  * Sf6Tasks

   options obligatoires :
    - count                     nombre de sous taches definies
    - enabled                   True/False

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces par defaut
    - tasktype                  type de la liste (normalement: 'sf6Task')
    - factory                   chemin vers sf6Design.exe
    - cmdextra                  options complementaires

   exemple :
    [Sf6Tasks]
    count           = 27
    tasktype        = sf6Task
    enabled         = True
    comments        = sf6 tasks list dummy test
    logfile         = %(log_file)s
    factory         = C:\Program Files\Setup Factory 6.0\SUF60Design.exe
    cmdextra        =

  ** Sf6Task_x

   options obligatoires :
    - enabled                   True/False
    - project                   projet a set up factory

   options obligatoires si non definies par la section "mere"
    - factory                   chemin vers sf6Design.exe

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces
    - tasktype                  type 'sf6Task'
     OBLIGATOIRE si le type differe de celui de la section "mere"
    - cmdextra                  options complementaires

   les taches set up factory on un nombre variable d'options supplementaires
   qui seront directement fournies a setup factory; les noms de ces options
   sont entoures par le caractere '$'

   exemple :
    [Sf6Task_26]
    enabled         = True
    project         = %(sf6_file)s
    cmdextra        = /M                # minimiser l'application
    $topimage$      = GA\netasq\InstallScripts\Images\Install_top.bmp
    $sideimage$     = GA\netasq\InstallScripts\Images\Install_side.bmp
    $filesdir$      = %(bin_dir)s
    $installname$   = GlobalAdmin 1.0   # nom de l'archive auto-extractible
    $build$         = test script       # suffixe de l'archive


  * "raw task"
  
   les taches "raw" permettent de specifier une commande qui sera passe
   tel quelle au systeme (copie de fichier, suppression, etc..)

   options obligatoires :
    - enabled                   True/False
    - tasktype                  type 'rawTask'
    - arglen                    nombre d'arguments de la commande

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces par defaut
    - arg0..argX                arguments de la commande

   exemple :
    [Sf6Task_9]
    tasktype        = rawTask
    enabled         = True
    arglen          = 2
    arg0            = del /F /Q /S
    arg1            = "%(bin_dir)s\Documents\Entries"


  * "del task"
  
   une tache de suppression a ete introduite; en effet, le MS DOS est
   particulierement limite pour realiser cette tache.
   
   - la commande rmdir (anciennement deltree sous MS windows 9x) ne permet
    pas l'utilisation du wildcard *, et leve une erreur pour la suppression
    d'entit (fichier ou repertoire) non existante
   
   - la commande del peut etre utilis sur un repertoire inexistant, sais
    gerer les fichiers en lecture seule, mais se borne a vider recursivement
    le repertoire cible de son contenu; l'arborsecence demeure.
   
   La tache de suppression pallie ces manques, elle est tres utile pour
   nettoyer un repertoire avant de recuperer des fichiers via CVS, ou
   encore avant une compilation
   
   Si la cible fournie est un repertoire, celui-ci sera tout d'abord
   _entierement_ vid, plus supprim.

   options obligatoires :
    - enabled                   True/False
    - tasktype                  type 'delTask'
    - target                    entit (fichier ou repertoire) a suprrimer

   options complementaires :
    - comments                  commentaires
    - logfile                   fichier de traces par defaut

   exemple :
    [CvsTask_0]
    tasktype        = delTask
    enabled         = True
    comments        = nettoyage du repertoire contenant les sources
    target          = %(src_dir)s
